Magento2 plug-ins

Limitations

You cannot use plug-ins for:

• Final methods / classes
• Non-public methods
• Class methods (such as static methods)
• __construct
• Virtual types

Declare a plug-in

You declare a plugin for an object in the di.xml file for a module:

You must specify these elements:

• type name. A class, interface, or virtual type, which the plug-in observes.
• plugin name. An arbitrary plug-in name that identifies a plug-in. Also used to merge the configurations for the plug-in.
• plugin type. The name of a plug-in’s class or its virtual type. Use the following schema when you specify this element:VendorModulePlugin<ModelName>Plugin.
• plugin sortOrder. The order in which plug-ins that call the same method are run.
• plugin disabled. To disable a plug-in, set this element to true.

Prioritize plug-ins

Several conditions influence how plug-ins apply to the same class or interface:

• Whether a listener method in a plug-in should apply before, after, or around an original method.Use one or more of the following methods to extend or modify an original method’s behavior with the interception functionality:
  • Change the arguments of an original method using the before-listener.The before-listener also:
    • Does not require you to declare unused arguments from the original method. SeeMagentoFrameworkInterceptionInterceptor.php for details.
    • Returns nothing if it modifies no arguments.
  • Change the values returned by an original method using the after-listener.
  • Change both the arguments and returned values of an original method using the around-listener.Unlike before or after, the around listener prevents the execution of the original method.
  • Override an original method (which is referred to as a conflicting change).

    Overriding a class is a conflicting change. Extending a class’s behavior is a non-conflicting change.

• The sort order of a plug-in.This parameter defines the order in which the plug-ins that use the same type of listener and call the same method are run.

  If several plug-ins apply to the same original method, the following sequence is observed:

  • The before listener in a plug-in with the highest priority (that is, with the smallest value of sortOrder argument).
  • The around listener in a plug-in with the highest priority (that is, with the smallest value of sortOrder argument).
  • Other before listeners in plug-ins according to sort order specified for them (that is, from the smallest to the greatest value).
  • Other around listeners in plug-ins according to the sort order specified for them (that is, from the smallest to the greatest value).
  • The after listener in a plug-in with the lowest priority (that is, with the greatest value of sortOrder argument).
  • Other after listeners in plug-ins, in the reverse sort order specified for them (that is, from the greatest to the smallest value).

Example plug-ins

To change the arguments of an original method or add some behavior before an original method is called, use the before-listener method. The method should return the changed argument, or an array of arguments, if the original method had multiple arguments. If the method returns null, no arguments are changed.

Prefix the name of the original method with before as the following sample shows:

<?php

namespace MyModulePlugin;

class ProductPlugin
{
    public function beforeSetName(MagentoCatalogModelProduct $subject, $name)
    {
        return ['(' . $name . ')'];
    }
}
?>

To change the values returned by an original method or add some behavior after an original method is called, use the after-listener method.

Prefix the name of the original method with after as the following sample shows:

<?php

namespace MyModulePlugin;

class ProductPlugin
{
    public function afterGetName(MagentoCatalogModelProduct $subject, $result)
    {
        return '|' . $result . '|';
    }
}
?>

To change both the arguments and returned values of an original method or add some behavior before and after an original method is called, use the around-listener method.

Prefix the name of the original listener with around as the following sample shows:

<?php

namespace MyModulePlugin;

class ProductPlugin
{
    public function aroundSave(MagentoCatalogModelProduct $subject, Closure $proceed)
    {
        $this->doSmthBeforeProductIsSaved();
        $returnValue = $proceed();
        if ($returnValue) {
            $this->postProductToFacebook();
        }
        return $returnValue;
    }
}
?>

The around-listener method receives two parameters ($subject and $proceed), followed by the arguments belonging to an original method.

The $subject parameter provides access to all public methods of the original class.

The $proceed parameter calls the next plug-in or method.

Configuration inheritance

The configuration inheritance implies that a plug-in applied to a class or interface is derived by the classes or interfaces, which implement or inherit an original class or interface.

You can use the configuration inheritance to implement AOP-like functionality with plug-ins, for instance, to observe the same methods of all models.

You can override the plug-ins defined in the global scope by changing di.xml file of an area.